Interesting idea. Two unpolished questions:

• Do I understand correctly that the hooks are called for every iteration of the IO loop? Normally we'd only need the first to register the handle in the context. The handler will have to prevent repeated registrations. Maybe this is something to be configured when registering the hooks. This might get a bit more tricky when the same handle is used from multiple fibers. When transferred to a second fiber, the hook wouldn't be triggered, unless this unification logic explicitly considers fibers.

• How could a scheduler implementation remove handles from the watcher? I think what we'd roughly want is a weak reference from the Context so that unreferenced handles are automatically removed, given we can't possibly wait on them anywhere.

Thank you for looking into it!

The idea of introducing stream hooks allowing user space to implement a scheduler originates from a suggestion of Frode Børli a long time ago. I'm working on this as part of STF.

Do I understand correctly that the hooks are called for every iteration of the IO loop? Normally we'd only need the first to register the handle in the context. The handler will have to prevent repeated registrations. Maybe this is something to be configured when registering the hooks. This might get a bit more tricky when the same handle is used from multiple fibers. When transferred to a second fiber, the hook wouldn't be triggered, unless this unification logic explicitly considers fibers.

In the current iteration, poll() is called every time I/O is about to be performed on the given stream (so just before any I/O). The method is expected to return only when the stream is ready, so the I/O performed just after that will not block. The hook can implement multiplexing and concurrency by switching to another fiber while the stream is not ready.

The plan is to change this logic a bit, to make the system compatible with EdgeTriggered mode, which allows to register streams only once:

• Make fds non-blocking at stream creation
• Perform I/O optimistically before polling. When this results in EAGAIN, poll and try again (this is faster, and the fact that we only poll when I/O is not ready makes it compatible with EdgeTriggered mode)
• Add a new unwatch() method to let userspace remove the stream from the context when it's about to be closed

This allows userspace to register streams only once. Systems without EdgeTriggered can emulate it.

Handling concurrent accesses to the same stream (which leads to multiple fibers waiting for the same stream) is on my TODO, but I'm not sure how this should be handled yet. What's almost certain is that these accesses will needed to wait in higher layers, not in php_pollfd_for() (we can likely call poll() during parameter parsing when the stream is already being polled).

How could a scheduler implementation remove handles from the watcher? I think what we'd roughly want is a weak reference from the Context so that unreferenced handles are automatically removed, given we can't possibly wait on them anywhere.

Exactly. Right now the plan is to introduce an Io\Poll\WeakHandle so that we can register a stream without preventing it from closing, plus the Io\Hooks\Hooks::unwatch() method to allow the scheduler to cleanup when a stream is closed.

Edit: All of these have been implemented now.